<!DOCTYPE html>

<html>
  <head>
    <meta charset="utf-8">
    
    <title>numpy.random.Generator.multivariate_hypergeometric &mdash; NumPy v1.18 Manual</title>
    
    <link rel="stylesheet" type="text/css" href="../../../_static/css/spc-bootstrap.css">
    <link rel="stylesheet" type="text/css" href="../../../_static/css/spc-extend.css">
    <link rel="stylesheet" href="../../../_static/scipy.css" type="text/css" >
    <link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" >
    <link rel="stylesheet" href="../../../_static/graphviz.css" type="text/css" >
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../../../',
        VERSION:     '1.18.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false
      };
    </script>
    <script type="text/javascript" src="../../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../../_static/doctools.js"></script>
    <script type="text/javascript" src="../../../_static/language_data.js"></script>
    <script type="text/javascript" src="../../../_static/js/copybutton.js"></script>
    <link rel="author" title="About these documents" href="../../../about.html" >
    <link rel="index" title="Index" href="../../../genindex.html" >
    <link rel="search" title="Search" href="../../../search.html" >
    <link rel="top" title="NumPy v1.18 Manual" href="../../../index.html" >
    <link rel="up" title="Random Generator" href="../generator.html" >
    <link rel="next" title="numpy.random.Generator.multivariate_normal" href="numpy.random.Generator.multivariate_normal.html" >
    <link rel="prev" title="numpy.random.Generator.multinomial" href="numpy.random.Generator.multinomial.html" > 
  </head>
  <body>
<div class="container">
  <div class="top-scipy-org-logo-header" style="background-color: #a2bae8;">
    <a href="../../../index.html">
      <img border=0 alt="NumPy" src="../../../_static/numpy_logo.png"></a>
    </div>
  </div>
</div>


    <div class="container">
      <div class="main">
        
	<div class="row-fluid">
	  <div class="span12">
	    <div class="spc-navbar">
              
    <ul class="nav nav-pills pull-left">
        <li class="active"><a href="https://numpy.org/">NumPy.org</a></li>
        <li class="active"><a href="https://numpy.org/doc">Docs</a></li>
        
        <li class="active"><a href="../../../index.html">NumPy v1.18 Manual</a></li>
        

          <li class="active"><a href="../../index.html" >NumPy Reference</a></li>
          <li class="active"><a href="../../routines.html" >Routines</a></li>
          <li class="active"><a href="../index.html" >Random sampling (<code class="xref py py-mod docutils literal notranslate"><span class="pre">numpy.random</span></code>)</a></li>
          <li class="active"><a href="../generator.html" accesskey="U">Random Generator</a></li> 
    </ul>
              
              
    <ul class="nav nav-pills pull-right">
      <li class="active">
        <a href="../../../genindex.html" title="General Index"
           accesskey="I">index</a>
      </li>
      <li class="active">
        <a href="numpy.random.Generator.multivariate_normal.html" title="numpy.random.Generator.multivariate_normal"
           accesskey="N">next</a>
      </li>
      <li class="active">
        <a href="numpy.random.Generator.multinomial.html" title="numpy.random.Generator.multinomial"
           accesskey="P">previous</a>
      </li>
    </ul>
              
	    </div>
	  </div>
	</div>
        

	<div class="row-fluid">
      <div class="spc-rightsidebar span3">
        <div class="sphinxsidebarwrapper">
  <h4>Previous topic</h4>
  <p class="topless"><a href="numpy.random.Generator.multinomial.html"
                        title="previous chapter">numpy.random.Generator.multinomial</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="numpy.random.Generator.multivariate_normal.html"
                        title="next chapter">numpy.random.Generator.multivariate_normal</a></p>
<div id="searchbox" style="display: none" role="search">
  <h4>Quick search</h4>
    <div>
    <form class="search" action="../../../search.html" method="get">
      <input type="text" style="width: inherit;" name="q" />
      <input type="submit" value="search" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
          <div class="span9">
            
        <div class="bodywrapper">
          <div class="body" id="spc-section-body">
            
  <div class="section" id="numpy-random-generator-multivariate-hypergeometric">
<h1>numpy.random.Generator.multivariate_hypergeometric<a class="headerlink" href="#numpy-random-generator-multivariate-hypergeometric" title="Permalink to this headline">¶</a></h1>
<p>method</p>
<dl class="method">
<dt id="numpy.random.Generator.multivariate_hypergeometric">
<code class="sig-prename descclassname">Generator.</code><code class="sig-name descname">multivariate_hypergeometric</code><span class="sig-paren">(</span><em class="sig-param">colors</em>, <em class="sig-param">nsample</em>, <em class="sig-param">size=None</em>, <em class="sig-param">method='marginals'</em><span class="sig-paren">)</span><a class="headerlink" href="#numpy.random.Generator.multivariate_hypergeometric" title="Permalink to this definition">¶</a></dt>
<dd><p>Generate variates from a multivariate hypergeometric distribution.</p>
<p>The multivariate hypergeometric distribution is a generalization
of the hypergeometric distribution.</p>
<p>Choose <code class="docutils literal notranslate"><span class="pre">nsample</span></code> items at random without replacement from a
collection with <code class="docutils literal notranslate"><span class="pre">N</span></code> distinct types.  <code class="docutils literal notranslate"><span class="pre">N</span></code> is the length of
<code class="docutils literal notranslate"><span class="pre">colors</span></code>, and the values in <code class="docutils literal notranslate"><span class="pre">colors</span></code> are the number of occurrences
of that type in the collection.  The total number of items in the
collection is <code class="docutils literal notranslate"><span class="pre">sum(colors)</span></code>.  Each random variate generated by this
function is a vector of length <code class="docutils literal notranslate"><span class="pre">N</span></code> holding the counts of the
different types that occurred in the <code class="docutils literal notranslate"><span class="pre">nsample</span></code> items.</p>
<p>The name <code class="docutils literal notranslate"><span class="pre">colors</span></code> comes from a common description of the
distribution: it is the probability distribution of the number of
marbles of each color selected without replacement from an urn
containing marbles of different colors; <code class="docutils literal notranslate"><span class="pre">colors[i]</span></code> is the number
of marbles in the urn with color <code class="docutils literal notranslate"><span class="pre">i</span></code>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><dl class="simple">
<dt><strong>colors</strong><span class="classifier">sequence of integers</span></dt><dd><p>The number of each type of item in the collection from which
a sample is drawn.  The values in <code class="docutils literal notranslate"><span class="pre">colors</span></code> must be nonnegative.
To avoid loss of precision in the algorithm, <code class="docutils literal notranslate"><span class="pre">sum(colors)</span></code>
must be less than <code class="docutils literal notranslate"><span class="pre">10**9</span></code> when <em class="xref py py-obj">method</em> is “marginals”.</p>
</dd>
<dt><strong>nsample</strong><span class="classifier">int</span></dt><dd><p>The number of items selected.  <code class="docutils literal notranslate"><span class="pre">nsample</span></code> must not be greater
than <code class="docutils literal notranslate"><span class="pre">sum(colors)</span></code>.</p>
</dd>
<dt><strong>size</strong><span class="classifier">int or tuple of ints, optional</span></dt><dd><p>The number of variates to generate, either an integer or a tuple
holding the shape of the array of variates.  If the given size is,
e.g., <code class="docutils literal notranslate"><span class="pre">(k,</span> <span class="pre">m)</span></code>, then <code class="docutils literal notranslate"><span class="pre">k</span> <span class="pre">*</span> <span class="pre">m</span></code> variates are drawn, where one
variate is a vector of length <code class="docutils literal notranslate"><span class="pre">len(colors)</span></code>, and the return value
has shape <code class="docutils literal notranslate"><span class="pre">(k,</span> <span class="pre">m,</span> <span class="pre">len(colors))</span></code>.  If <em class="xref py py-obj">size</em> is an integer, the
output has shape <code class="docutils literal notranslate"><span class="pre">(size,</span> <span class="pre">len(colors))</span></code>.  Default is None, in
which case a single variate is returned as an array with shape
<code class="docutils literal notranslate"><span class="pre">(len(colors),)</span></code>.</p>
</dd>
<dt><strong>method</strong><span class="classifier">string, optional</span></dt><dd><p>Specify the algorithm that is used to generate the variates.
Must be ‘count’ or ‘marginals’ (the default).  See the Notes
for a description of the methods.</p>
</dd>
</dl>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><dl class="simple">
<dt><strong>variates</strong><span class="classifier">ndarray</span></dt><dd><p>Array of variates drawn from the multivariate hypergeometric
distribution.</p>
</dd>
</dl>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<dl class="simple">
<dt><a class="reference internal" href="numpy.random.hypergeometric.html#numpy.random.hypergeometric" title="numpy.random.hypergeometric"><code class="xref py py-obj docutils literal notranslate"><span class="pre">hypergeometric</span></code></a></dt><dd><p>Draw samples from the (univariate) hypergeometric distribution.</p>
</dd>
</dl>
</div>
<p class="rubric">Notes</p>
<p>The two methods do not return the same sequence of variates.</p>
<p>The “count” algorithm is roughly equivalent to the following numpy
code:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">choices</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">repeat</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">colors</span><span class="p">)),</span> <span class="n">colors</span><span class="p">)</span>
<span class="n">selection</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">choice</span><span class="p">(</span><span class="n">choices</span><span class="p">,</span> <span class="n">nsample</span><span class="p">,</span> <span class="n">replace</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
<span class="n">variate</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">bincount</span><span class="p">(</span><span class="n">selection</span><span class="p">,</span> <span class="n">minlength</span><span class="o">=</span><span class="nb">len</span><span class="p">(</span><span class="n">colors</span><span class="p">))</span>
</pre></div>
</div>
<p>The “count” algorithm uses a temporary array of integers with length
<code class="docutils literal notranslate"><span class="pre">sum(colors)</span></code>.</p>
<p>The “marginals” algorithm generates a variate by using repeated
calls to the univariate hypergeometric sampler.  It is roughly
equivalent to:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">variate</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">zeros</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">colors</span><span class="p">),</span> <span class="n">dtype</span><span class="o">=</span><span class="n">np</span><span class="o">.</span><span class="n">int64</span><span class="p">)</span>
<span class="c1"># `remaining` is the cumulative sum of `colors` from the last</span>
<span class="c1"># element to the first; e.g. if `colors` is [3, 1, 5], then</span>
<span class="c1"># `remaining` is [9, 6, 5].</span>
<span class="n">remaining</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">cumsum</span><span class="p">(</span><span class="n">colors</span><span class="p">[::</span><span class="o">-</span><span class="mi">1</span><span class="p">])[::</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span>
<span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">colors</span><span class="p">)</span><span class="o">-</span><span class="mi">1</span><span class="p">):</span>
    <span class="k">if</span> <span class="n">nsample</span> <span class="o">&lt;</span> <span class="mi">1</span><span class="p">:</span>
        <span class="k">break</span>
    <span class="n">variate</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">hypergeometric</span><span class="p">(</span><span class="n">colors</span><span class="p">[</span><span class="n">i</span><span class="p">],</span> <span class="n">remaining</span><span class="p">[</span><span class="n">i</span><span class="o">+</span><span class="mi">1</span><span class="p">],</span>
                               <span class="n">nsample</span><span class="p">)</span>
    <span class="n">nsample</span> <span class="o">-=</span> <span class="n">variate</span><span class="p">[</span><span class="n">i</span><span class="p">]</span>
<span class="n">variate</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span> <span class="o">=</span> <span class="n">nsample</span>
</pre></div>
</div>
<p>The default method is “marginals”.  For some cases (e.g. when
<em class="xref py py-obj">colors</em> contains relatively small integers), the “count” method
can be significantly faster than the “marginals” method.  If
performance of the algorithm is important, test the two methods
with typical inputs to decide which works best.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.18.0.</span></p>
</div>
<p class="rubric">Examples</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">colors</span> <span class="o">=</span> <span class="p">[</span><span class="mi">16</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">4</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">seed</span> <span class="o">=</span> <span class="mi">4861946401452</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">gen</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">Generator</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">PCG64</span><span class="p">(</span><span class="n">seed</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">gen</span><span class="o">.</span><span class="n">multivariate_hypergeometric</span><span class="p">(</span><span class="n">colors</span><span class="p">,</span> <span class="mi">6</span><span class="p">)</span>
<span class="go">array([5, 0, 1])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">gen</span><span class="o">.</span><span class="n">multivariate_hypergeometric</span><span class="p">(</span><span class="n">colors</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="n">size</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>
<span class="go">array([[5, 0, 1],</span>
<span class="go">       [2, 2, 2],</span>
<span class="go">       [3, 3, 0]])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">gen</span><span class="o">.</span><span class="n">multivariate_hypergeometric</span><span class="p">(</span><span class="n">colors</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="n">size</span><span class="o">=</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">))</span>
<span class="go">array([[[3, 2, 1],</span>
<span class="go">        [3, 2, 1]],</span>
<span class="go">       [[4, 1, 1],</span>
<span class="go">        [3, 2, 1]]])</span>
</pre></div>
</div>
</dd></dl>

</div>


          </div>
        </div>
          </div>
        </div>
      </div>
    </div>

    <div class="container container-navbar-bottom">
      <div class="spc-navbar">
        
      </div>
    </div>
    <div class="container">
    <div class="footer">
    <div class="row-fluid">
    <ul class="inline pull-left">
      <li>
        &copy; Copyright 2008-2019, The SciPy community.
      </li>
      <li>
      Last updated on Feb 20, 2020.
      </li>
      <li>
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.4.2.
      </li>
    </ul>
    </div>
    </div>
    </div>
  </body>
</html>